Part 1

原文：https://zhuanlan.zhihu.com/p/527786727

作者：陶建辉, 2021年10月18日于北京

我们在实际工作中，经常要做各种review (评审), 包括设计、代码、文档等等。大家习惯性的做法，是召集相关的人开会，内容的负责人会走读一次，介绍一下，为什么这么做，这么写，然后汇集大家的意见做些调整。通过多年的实践，我认为这套方法是走过场的，是形式主义的review，难以达到review的目的。表现在几个方面：

  1. review的人没有做充足准备，思路只能跟着主讲人的思路跑，发现的问题往往是违反规范，或其他显而易见的问题；
  2. review的人提的问题是现场提的，不是经过思考提出来的，因此有可能是不完整的，甚至不合逻辑或错误的；
  3. 参与开会的人，很多是心不在焉的，整个会议是一句话都不说的，完全没有产出。

那么怎么做有效果的review呢？我们需要做到以下几点：

  1. 内容负责人提前准备好内容：对照<Amazon 的秘密管理武器 - 「6页备忘录」> 检查一下内容是否满足要求。对于特别具体的文档，比如背景、解决的问题或需求大家都十分清晰的，准备的内容可以直奔主题（但建议用参考文档的方式放在内容最后，以免有不熟悉了解的人）
  2. 在Confluence的文档里直接@，或飞书通知相关的人进行review，并给出需要收到review回复的时间。
  3. 所有需要review的人，在指定的时间之前，仔细阅读内容，将自己的反馈直接写在 confluence或飞书文档上。
  4. 内容负责人收到review反馈后，看反馈的意见是否可以接受或持不同意见。对于可以接受的，直接接受，更新内容。对于不接受的，或有疑惑的，可以在confluence或飞书里互动，但互动回合不宜超过3次，过多的话，最好语音沟通，或进行会议。
  5. 内容负责人如果觉得大家的反馈都被吸收、或疑惑都已经解决、澄清，那么无需组织任何会议，review就完成了。
  6. 如果有书面交流争执不下或模糊不清的，再决定召开会议。召集会议，参会的人，是必须已经提供过书面反馈意见的。没有提过意见的，不应该邀请参会。

原则上，任何交流沟通都应该遵循《如何高效的沟通交流》里定的原则，而且要以书面文字为主，万不得已，不采用会议方式。

这么review的好处是：

  1. 每个人是真正的review了，而且反馈、互动在系统里都有记录；
  2. 任何时候，任何人都可以参与进讨论，而且不会讨论重复的问题；
  3. 尽可能不组织会议，这样便于远程办公，便于不同时区的人协同工作；
  4. 避免滥竽充数，只听不出的人参加会议。

那么有人总认为，只有会议、语音才能给大家解释清楚自己做的工作、文档、设计或代码，这是错误的认识。任何一项工作、文档、设计等等就必须用文字或代码清晰的、逻辑的表达，只要有模糊不清的地方，一定是自己没有想清楚。你可以明确告知大家，某一块没有想清楚，还模糊，求助大家，或等自己想明白，再清晰的用文字表达，之后请大家review。

Part 2

The Code Review Pyramid

URL：https://www.morling.dev/blog/the-code-review-pyramid/

code review pyramid

FAQ

  • Why is it a pyramid?

    The lower parts of the pyramid should be the foundation of a code review and take up the most part of it.

  • Hey, that’s a triangle!

    You might think so, but it’s a pyramid from the side.

  • Which tool did you use for creating the drawing?

    Excalidraw.

好的测试可以作为文档。应该专门设计测试，包括形式化验证、模糊测试、突变测试、单元测试，最后是（相当有限的）集成测试，好的测试比文档更重要。

好的函数签名和变量名称也可以作为文档。好的产品需要最少的文档。但对于糟糕的产品，再多的文档也是不够的。

错误的文档重复了代码所说的内容。好的文档提供包含代码中缺少的上下文。

应该区分为项目的开发者准备的文档和为项目的用户准备的文档。

前者应该最小化，并用好的测试可以作为“主要”的文档。第二种需要某种来自人类的审查，以确保用户知道如何使用你的产品。

对于开发者文档，用英文重复变量名称的注释不是文档。

开发者的文档确实有用处，尽管它取决于项目的类型和你的代码库的大小。好的文档可以为大型代码库中更复杂的项目提供急需的背景，特别是当你有跨领域的团队时。如果其他一些团队在类/方法文档中甚至只有简短的快速文档，为他们的代码/类的关键部分提供上下文（为什么/目的，而不是如何），这将节省很多时间。对于一些直接的CRUD API项目，肯定不需要开发者文档。

很多底层的工作也可以自动化；有一些静态代码分析工具，用于分析复杂性、性能、文档、DRY、安全等等。

我将文档放在比测试更低的级别，因为前者是一个面向用户的“合同”，因此与一些写得不好的测试相比，以后可能更难更改。最后，我认为金字塔是一个对话的开始，如果某个团队有意识地得出结论，他们更喜欢不同的优先级，这也很酷。

根据我的经验，通过早期审查代码可以节省大量的时间。我同意API语义部分--你说要在代码审查中花最多时间的地方--是极其重要的 我只是认为在所有的代码都写好之前进行审查会更好。例如，设计文件或带有接口定义的初步PRS。

说得好，在理想情况下，像API语义这样的关键方面已经在前期讨论过并达成一致，在代码审查中只需要快速验证。这个金字塔是基于我在开源开发中的经验，在那里并不总是如此；经常有人在没有事先讨论的情况下提出一个大的变化或新的功能（尽管所有的建议都反对这样做）